Updates in readme documentation #744
Conversation
shimilgithub
commented
Nov 2, 2023
shimilgithub
commented
- Update Readme file of Vachan API #741
README.md
Outdated
| The server application that provides REST APIs to interact with the underlying Databases (SQL and Graph) and modules in Vachan-Engine. | ||
| <h1 align="center"> | ||
| <br> | ||
| <a href="http://www.amitmerchant.com/electron-markdownify"><img src="https://api.vachanengine.org/static/images/Logo.svg" alt="vachanapi" width="200"></a> | ||
| <br> | ||
| Vachan API | ||
| <br> | ||
| </h1> | ||
| <h4 align="center">Unified API for <a href="https://api.vachanengine.org/" target="_blank">Vachan-Engine applications</a></h4> | ||
| <p align="center"> | ||
| •<a href="#implementation-details"> Implementation Details</a> • | ||
| <a href="#start-app-with-docker">Start App</a> • | ||
| <a href="#set-up-locally-for-development-and-testingwithout-docker">Setup</a> • | ||
| <a href="#license">License</a> | ||
| </p> |
There was a problem hiding this comment.
Markdown format is often used for its simplicity. I thinks its better to stick to it and avoid embedded HTML as much as possible.
In these we can use markdown features to get decent level of formatting
# big heading
## small heading
### smaller heading
[link-text](link-target)
- list item1
- list item2
- sub item1
- sub item2
big heading
small heading
smaller heading
- list item1
- list item2
- sub item1
- sub item2
There was a problem hiding this comment.
@kavitharaju Markdown doesn't directly provide the option to align text and resize images. HTML is used for this purpose.
There was a problem hiding this comment.
How critical is aligning text in a readme?
About image resizing, yes you could use it places where markdown support is not there. But keep it limited to that
There was a problem hiding this comment.
Another thing is I am reviewing this PR with little context. The parent issue says
Enhance the Readme file of Vachan API by providing comprehensive and clear documentation.
Which in my opinion doesn't say anything! What are we making more comprehensive and clear here? The issue itself should be more specific and to the point than a too generalized statement like this.
And honestly I doubt the changes in the PR is making anything more comprehensive and clear.
There was a problem hiding this comment.
Something I liked here is the idea of adding a gif. Makes the document more interesting. But is the API docs the best thing we can show in it? May be... I dont know..
There was a problem hiding this comment.
How critical is aligning text in a readme? About image resizing, yes you could use it places where markdown support is not there. But keep it limited to that
Text alignment is required only at the single line description("Unified API for VE applications") and the direct links mentioned below that line.
There was a problem hiding this comment.
Does it really have to be center? Why?
There was a problem hiding this comment.
to keep it properly down to the logo(which is kept in middle)
There was a problem hiding this comment.
Another thing is I am reviewing this PR with little context. The parent issue says
Enhance the Readme file of Vachan API by providing comprehensive and clear documentation.
Which in my opinion doesn't say anything! What are we making more comprehensive and clear here? The issue itself should be more specific and to the point than a too generalized statement like this.
And honestly I doubt the changes in the PR is making anything more comprehensive and clear.
will modify issue description
shimilgithub
dismissed stale reviews from Joel-Joseph-George and AthulyaMS
via
3bac68f
| <h1 align="center"> | ||
| <br> | ||
| <a href="http://www.amitmerchant.com/electron-markdownify"><img src="https://api.vachanengine.org/static/images/Logo.svg" alt="vachanapi" width="200"></a> | ||
| <br> | ||
| Vachan API | ||
| <br> | ||
| </h1> |
There was a problem hiding this comment.
Can't h1 , br be avoided?
There was a problem hiding this comment.
When I remove h1 tag, logo image goes to left like this. Can I keep like that only or can I use div container to keep image centrally aligned.
There was a problem hiding this comment.
How about not keeping it centrally aligned? And I dont know what is the point of this much care for formatting a readme file...
<img src="https://api.vachanengine.org/static/images/Logo.svg" alt="vachanapi" width="100"></a>
# VACHAN API
VACHAN API
There was a problem hiding this comment.
I have asked to update readme similar to this reference
